Sending from other systems
Anything on the local network that can call a web address can send a message through the driver: an alarm panel, a network video recorder, a PLC, Home Assistant or a script. It can send one of your templates, or a message of its own. The message goes to the same people, webhooks and inbox as one sent from Crestron Home programming.
The send address and token​
Open the API tab in the setup app. It shows:
- the Send URL, which is the processor's address followed by
/cws/, the driver instance's path, and/send; - the Send token, which every caller must add to the address as
?token=.
Choose whether callers use http or https. With https, the caller must accept the processor's own certificate. Use Copy to take the address or the token. New token replaces the token straight away, and anything still using the old one is refused. Do that if the token gets into the wrong hands.
Anyone on the network who has the token can send messages to the household. Give it only to the systems that need it. The downloads on the API tab contain the token too.
Sending a template​
The Examples section of the API tab has a ready-made link for every template, with a cURL command for macOS and Linux and a PowerShell command for Windows. Copy the one you need into the other system.
As a link (GET), for devices that can only call a URL:
http://192.168.1.10/cws/<path>/send?token=<token>&template=Garage%20open&var.door=side
As a POST with a JSON body:
curl -X POST "http://192.168.1.10/cws/<path>/send?token=<token>" \
-d '{"template": "Garage open", "vars": {"door": "side"}}'
In Windows PowerShell, curl is a different command. Use Invoke-RestMethod instead:
Invoke-RestMethod -Method Post -Uri "http://192.168.1.10/cws/<path>/send?token=<token>" `
-ContentType 'application/json' -Body '{"template": "Garage open", "vars": {"door": "side"}}'
var.door=side in a link, or "vars": {"door": "side"} in a body, fills {var:door} in the template.
Sending a message of your own​
Send a subject and body instead of a template name:
{
"subject": "Front gate left open",
"body": "The gate has been open since 18:40.",
"level": "warning",
"tag": "gate"
}
The same fields work as query parameters in a link. Every field except subject and body is optional:
| Field | What it does |
|---|---|
template | Send this template. Use it instead of subject and body. |
vars | Values for the template's {var:name} placeholders. In a link: var.name=value. |
subject, body | The message. |
level | info, notice, warning or critical. Default info. |
channels | The people and webhooks to send to, by their id. The ids are listed in the OpenAPI download. Without it, the level decides. In a link, separate them with commas. |
link, linkTitle | A web address and its text. It must start with http:// or https://. |
tag | A key that replaces an older message with the same tag, and stops repeats. |
inbox | false to send without keeping it in the inbox. |
keepFor | Minutes before the inbox drops it. 0 keeps it until someone clears it. |
protected | true to make clearing it need the clear code. |
actions | Up to three buttons, each {"label": "…", "confirm": "…", "event": "…"}. POST only. |
A message can be up to 64 KB.
Answers​
The driver answers in JSON:
| Status | Meaning |
|---|---|
200 | Accepted. The answer says how many deliveries were queued, whether it went in the inbox, and any notes, such as a person in quiet hours. If notifications or the template are switched off, Accepted is false with the reason. |
400 | Something is wrong with the message. The answer lists what. |
401 | The token is missing or wrong. |
402 | The driver isn't licensed, so nothing was sent. |
405 | Use GET or POST. |
Postman and OpenAPI​
The API tab has two downloads:
- Download Postman collection: a Postman collection (v2.1) with one request per template. In Postman, choose
Import and pick the file. The collection keeps the address and token in variables called
baseUrlandtoken. - Download OpenAPI description: the same description in OpenAPI 3, for other tools.
Both are made from the setup as it is now. Download them again after you add or rename templates.